REST APIs ansprechen

Eine REST API (Representational State Transfer) ist die heute übliche Methode wie Softwaresysteme miteinander kommunizieren. Wenn ein ERP-System, ein CRM, ein Bezahldienst oder ein Cloudtool eine Schnittstelle anbietet, ist es fast immer eine REST API. In 42°OS sprichst du REST APIs über den Post Agent an.

---

Das Grundprinzip

Eine REST API funktioniert wie ein Gespräch nach festen Regeln:

• Du schickst eine Anfrage (Request) an eine bestimmte URL
• Die URL identifiziert eine Ressource: https://api.example.com/kunden/42
• Die HTTP-Methode bestimmt was du tun willst
• Du bekommst eine Antwort (Response) mit einem Statuscode und meistens einem JSON-Body zurück

---

HTTP-Methoden

Methode	Bedeutung	Beispiel
GET	Daten abrufen	Kunden-Datensatz lesen
POST	Neuen Datensatz anlegen	Bestellung erstellen
PUT	Datensatz vollständig ersetzen	Kundendaten aktualisieren
PATCH	Datensatz teilweise aktualisieren	Nur Status ändern
DELETE	Datensatz löschen	Bestellung stornieren

---

HTTP-Statuscodes

Die Antwort enthält immer einen dreistelligen Statuscode:

Bereich	Bedeutung	Beispiele
2xx	Erfolg	200 OK, 201 Created, 204 No Content
3xx	Weiterleitung	301 Moved Permanently
4xx	Fehler auf deiner Seite	400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
5xx	Fehler auf der Gegenseite	500 Internal Server Error, 503 Service Unavailable

Ein Workflow sollte auf den Statuscode reagieren — ein 401 bedeutet Authentifizierungsproblem, ein 404 bedeutet die Ressource existiert nicht, ein 500 ist ein temporäres Problem beim Zielsystem.

---

Authentifizierungsverfahren

Die meisten APIs erfordern eine Form der Authentifizierung. Die gängigsten Verfahren:

API Key im Header

Einfachstes Verfahren. Ein geheimer Schlüssel wird bei jeder Anfrage im Header mitgeschickt:

{
  "post_url": "https://api.example.com/v1/daten",
  "method": "get",
  "headers": {
    "X-API-Key": "{% credential mein_api_key %}"
  }
}

Der tatsächliche Schlüssel wird im Credential-Store hinterlegt und per {% credential name %} eingebunden — er erscheint nie im Klartext in der Konfiguration.

Bearer Token (OAuth 2.0)

Verbreitet bei modernen APIs (Microsoft, Google, Salesforce, ...). Ein Token wird im Authorization-Header übermittelt:

{
  "headers": {
    "Authorization": "Bearer {% credential oauth_token %}"
  }
}

Bei OAuth 2.0 hat das Token eine begrenzte Gültigkeit. Je nach API muss ein separater Workflow das Token regelmäßig erneuern (Token Refresh) und im Credential-Store aktualisieren.

Basic Auth

Benutzername und Passwort werden Base64-kodiert im Header übermittelt. Heute selten bei modernen APIs, noch anzutreffen bei älteren Systemen:

{
  "headers": {
    "Authorization": "Basic {% credential basic_auth_encoded %}"
  }
}

Der Credential-Eintrag enthält den bereits Base64-kodierten String benutzername:passwort.

API Key als Query-Parameter

Manche älteren APIs erwarten den Schlüssel in der URL:

{
  "post_url": "https://api.example.com/daten?api_key={% credential api_key %}&format=json",
  "method": "get"
}

---

Der Post Agent in 42°OS

Der Post Agent übernimmt alle HTTP-Anfragen. Kernkonfiguration:

{
  "post_url": "https://api.example.com/v1/bestellungen",
  "method": "post",
  "content_type": "json",
  "payload": {
    "kunden_id": "{{ kunden_id }}",
    "artikel": "{{ artikel }}",
    "menge": "{{ menge }}"
  },
  "headers": {
    "Authorization": "Bearer {% credential api_token %}"
  },
  "emit_messages": true
}

Wichtige Optionen:

Option	Bedeutung
post_url	Ziel-URL, Liquid-Templates möglich
method	get, post, put, patch, delete
content_type	json, form, xml oder MIME-Typ
payload	Request-Body oder Query-Parameter bei GET
headers	Zusätzliche HTTP-Header
emit_messages	Antwort als Nachricht weitergeben
output_mode	clean (nur Antwort) oder merge (Antwort + Eingangsnachricht)

Antwort verarbeiten

Wenn emit_messages: true gesetzt ist, gibt der Agent eine Nachricht mit drei Feldern aus:

{
  "status": 200,
  "headers": {
    "Content-Type": "application/json"
  },
  "body": "{\"id\": \"ORD-12345\", \"status\": \"created\"}"
}

body ist ein String — für die Weiterverarbeitung muss er per JSON Parse Agent in ein Objekt umgewandelt werden.

GET-Anfrage mit Parametern

Bei GET werden Parameter als Query-String an die URL angehängt:

{
  "post_url": "https://api.example.com/v1/kunden",
  "method": "get",
  "payload": {
    "status": "aktiv",
    "limit": "50",
    "since": "{{ seit_datum }}"
  },
  "headers": {
    "Authorization": "Bearer {% credential api_token %}"
  },
  "emit_messages": true
}

Ergibt die URL: https://api.example.com/v1/kunden?status=aktiv&limit=50&since=2026-01-01

---

Dynamische URLs mit Liquid

Die post_url unterstützt Liquid-Ausdrücke — hilfreich wenn die ID einer Ressource Teil der URL ist:

{
  "post_url": "https://api.example.com/v1/kunden/{{ kunden_id }}/bestellungen",
  "method": "get"
}

---

Fehlerbehandlung

Ein häufiges Muster: nach dem Post Agent einen Switch Agent einsetzen der auf den Statuscode reagiert:

Post Agent
    ↓
Switch Agent: status == 200 → weiterverarbeiten
             status == 401 → Fehler-Workflow (Token abgelaufen?)
             status == 404 → Ressource nicht gefunden
             status >= 500 → Retry oder Benachrichtigung

---

Sicherheit

Alle Credentials — API Keys, Tokens, Passwörter — gehören in den Credential-Store der Plattform, nicht direkt in die Agent-Konfiguration. Nur der Name des Credential-Eintrags erscheint in der Konfiguration, der Wert selbst ist verschlüsselt gespeichert.

Ausschließlich HTTPS-URLs verwenden. HTTP-Verbindungen übertragen Credentials unverschlüsselt.